.Dd Dec 26, 2023
.Dt IMAPFILTER 1
.Os
.Sh NAME
.Nm imapfilter
.Nd mail filter
.Sh SYNOPSIS
.Nm
.Op Fl inVv
.Op Fl c Ar configfile
.Op Fl d Ar debugfile
.Op Fl e Ar 'command'
.Op Fl l Ar logfile
.Op Fl p Ar pidfile
.Op Fl t Ar truststore
.Sh DESCRIPTION
.Nm
is a mail filtering utility. It connects to remote mail servers using the
Internet Message Access Protocol (IMAP), sends searching queries to the server
and processes mailboxes based on the results. It can be used to delete, copy,
move, flag, etc. messages residing in mailboxes at the same or different mail
servers. The 4rev1 and 4 versions of the IMAP protocol are supported.
.Pp
The command line options of
.Xr imapfilter 1
are as follows:
.Bl -tag -width Ds
.It Fl c Ar configfile
Path to the configuration file to read, or the
.Sq -
character to read the configuration from the standard input stream.  The
default is
.Pa $HOME/.imapfilter/config.lua .
.It Fl d Ar debugfile
File that contains debugging information about the full communication with the
server, along with other inner workings' details.
.It Fl e Ar 'command'
May be used to enter
.Dq one line
of configuration, while it is also possible to pipe a full configuration as a
string.
When this option is used, a configuration file will not be loaded.
.It Fl i
Enters interactive mode after executing the configuration file.
.It Fl l Ar logfile
File that contains logs of error messages produced.
.It Fl n
This option enables the so called dry-run mode, and any actions that would
result in changes to the server do not actually take place. So the requests
that would modify any data are not sent to the server, even though
informational messages about these actions are still printed.

Any other methods, that only receive data from the server, are performed as
normal, such as for example the searching methods. Note, that the number of
messages an action is reported to be applied upon, might differ between dry-run
mode and the normal execution, and this is expected as in the latter case the
data on the server are continuously altered by subsequent actions.
.It Fl t Ar truststore
The path to the system's SSL CA TrustStore directory or file. SSL connections
will be validated using the CA certificates found in this directory or file,
and when this is not possible, the local
.Pa $HOME/.imapfilter/certificates
file will be used.  The default CA directory is
.Pa /etc/ssl/certs/ ,
and the default CA file is
.Pa /etc/ssl/cert.pem .
.It Fl p Ar pidfile
Write the process ID (PID) to this file on startup, and delete it on exit.
.It Fl V
Displays version and copyright information.
.It Fl v
Enables printing of some brief details of the communication with the server.
.El
.Sh ENVIRONMENT
.Bl -tag -width Ds
.It Ev HOME
User's home directory.
.It Ev IMAPFILTER_HOME
Program's configuration directory, which overrides the default
.Pa $HOME/.imapfilter/ .
.El
.Sh FILES
.Bl -tag -width Ds
.It Pa $HOME/.imapfilter/config.lua
Default configuration file. Because this file may contain sensitive data such
as user passwords, the recommended permissions are read/write for the user, and
not accessible by others.
.It Pa $HOME/.imapfilter/certificates
File where the SSL certificates are stored.
.El
.Sh SEE ALSO
.Xr imapfilter_config 5
.Sh CONFORMING TO
.Bl -tag -width Ds
.It IMAP4rev1:
RFC 3501, RFC 3348, RFC 2683, RFC 2595, RFC 2342, RFC 2195,
RFC 2177, RFC 5161, RFC 6855
.It IMAP4:
RFC 1730
.El
